feat: #2228 Add tool origin tracking to ToolCallItem and ToolCallOutputItem by habema · Pull Request #2242 · openai/openai-agents-python

habema · 2025-12-28T11:45:36Z

Adds tool_origin field to ToolCallItem and ToolCallOutputItem to track where function tools came from (regular functions, MCP servers, or agent-as-tool). This helps with debugging and tracing which MCP server handled a call when using multiple servers.

The tool_origin is a ToolOrigin object that contains:

type: The origin type (FUNCTION, MCP, or AGENT_AS_TOOL)
mcp_server_name: The MCP server name (only set for MCP tools)
agent_as_tool_name: The agent name (only set for agent-as-tool)

New tests added

Closes #2228

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/agents/run.py

seratch

Our current top priority is to merge HITL enhancement, which changes runner internals a lot. So, we may ask you to resolve the conflicts after the big PR is merged.

seratch · 2026-01-05T03:32:27Z

src/agents/agent.py


            return run_result.final_output

+        # Set origin tracking on the FunctionTool created by @function_tool


it seems the code comment here is incorrect

Changed to Set origin tracking on run_agent (the FunctionTool returned by @function_tool) for more clarity

seratch · 2026-01-05T03:34:38Z

src/agents/tool.py

+    mcp_server_name: str | None = None
+    """The name of the MCP server. Only set when type is MCP."""
+
+    agent_as_tool_name: str | None = None


This object may receive feature requests to have more properties, so simply having the reference to the agent object may be fine. Same for mcp_server_name too

Makes sense. I've changed the implementation so that the objects are stored. I'm not too sure about the custom __repr__, below is an example of what ToolOrigin would look like with and without it. Let me know what you think.

Without a __repr__ method, ToolOrigin would look like:

MCP
ToolOrigin(type=<ToolOriginType.MCP: 'mcp'>, mcp_server=<tests.mcp.helpers.FakeMCPServer object at 0x...>, agent_as_tool=None)

Agent as tool:
ToolOrigin(type=<ToolOriginType.AGENT_AS_TOOL: 'agent_as_tool'>, mcp_server=None, agent_as_tool=Agent(name='test_agent', handoff_description=None, tools=[], mcp_servers=[], mcp_config={}, instructions='Test agent', prompt=None, handoffs=[], model=<tests.fake_model.FakeModel object at 0x...>, model_settings=ModelSettings(...), input_guardrails=[], output_guardrails=[], output_type=None, hooks=None, tool_use_behavior='run_llm_again', reset_tool_choice=True))

Function:
ToolOrigin(type=<ToolOriginType.FUNCTION: 'function'>, mcp_server=None, agent_as_tool=None)

With the custom __repr__:

ToolOrigin(type='mcp', mcp_server_name='test_server')

ToolOrigin(type='agent_as_tool', agent_as_tool_name='test_agent')

ToolOrigin(type='function')

seratch · 2026-01-22T01:25:13Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8b2d12a8b0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/agents/tool.py

- Add ToolOriginType enum and ToolOrigin dataclass - Add _tool_origin field to FunctionTool - Set tool_origin for MCP tools and agent-as-tool - Extract and set tool_origin in ToolCallItem and ToolCallOutputItem creation - Add comprehensive tests for tool origin tracking

habema · 2026-03-01T11:50:28Z

@codex review please

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8776b02295

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/agents/run_internal/run_loop.py

src/agents/run_state.py

…MA_VERSIONS

habema · 2026-03-01T12:04:29Z

@codex review a final time please

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e96186113b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/agents/run_internal/run_loop.py

habema · 2026-03-01T12:19:53Z

@codex review please

chatgpt-codex-connector · 2026-03-01T12:25:52Z

Codex Review: Didn't find any major issues. 🎉

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

seratch · 2026-03-01T22:45:25Z

Thanks for working on this. I did a few additional codex reviews and it pointed the following things out. Also, I feel this change requires a minor version bump, so we won't immediately merge it.

On src/agents/run_state.py#L696

tool_origin for agent.as_tool() is serialized/deserialized by agent name only. Agent.name is not unique, so this breaks as soon as an orchestrator has two nested agents with the same name. I reproduced this locally with two different dup agents: after RunState.to_json()/from_json(), the restored tool_origin.agent_as_tool pointed to the first one in the map, not the one that actually handled the tool call. That makes the persisted provenance incorrect.

On src/agents/run_internal/tool_execution.py#L875

The new provenance is preserved for rejected/executed tool results, but not for the pending approval path. When needs_approval=True and approval_status is None, we create a ToolApprovalItem without tool_origin, so callers still cannot tell whether the pending tool came from a local function tool, MCP tool, or agent.as_tool(). If we want tool_origin to be a reliable provenance signal, it needs to be attached to approval interruptions as well.

1. **Agent-as-tool identity** – Switched from `agent.name` to `agent_index` in serialization so duplicate agent names are handled correctly. 2. **`_build_agent_map`** – Now returns `(agent_map, agent_list)` with `id()`-based visited tracking. 3. **`ToolApprovalItem`** – Added `tool_origin` and `release_agent` for provenance on pending approvals. 4. **RunState** – Added `_starting_agent` and optional `root_agent` for correct agent graph traversal during serialization.

habema · 2026-03-01T23:12:40Z

@seratch I understand that the scale of changes here requires a minor bump, no worries. I've addressed your comments, let me know if there are any others.

chatgpt-codex-connector bot reviewed Dec 28, 2025

View reviewed changes

src/agents/run.py Outdated Show resolved Hide resolved

habema added a commit to habema/openai-agents-python that referenced this pull request Dec 28, 2025

fix codex review in openai#2242 (review)

65ba07c

seratch added enhancement New feature or request feature:core feature:mcp labels Jan 5, 2026

seratch reviewed Jan 5, 2026

View reviewed changes

seratch added this to the 0.7.x milestone Jan 6, 2026

seratch added the skip-stale label Jan 8, 2026

seratch modified the milestones: 0.7.x, 0.8.x Jan 22, 2026

chatgpt-codex-connector bot reviewed Jan 22, 2026

View reviewed changes

src/agents/tool.py Show resolved Hide resolved

seratch marked this pull request as draft January 22, 2026 23:25

seratch modified the milestones: 0.8.x, 0.9.x Jan 28, 2026

k1eran mentioned this pull request Jan 29, 2026

Propagate tool description to ToolCallItem #2379

Closed

github-actions bot added dependencies documentation Improvements or additions to documentation feature:chat-completions feature:lite-llm feature:realtime feature:sessions feature:tracing feature:voice project labels Feb 5, 2026

habema force-pushed the feat/track-tool-origin branch from 1f0af9c to 8cbf13f Compare February 5, 2026 12:07

habema force-pushed the feat/track-tool-origin branch from 8cbf13f to edbec4e Compare February 5, 2026 12:23

fix memory leak in code review and add test

e1b6357

habema marked this pull request as ready for review February 5, 2026 12:35

seratch modified the milestones: 0.9.x, 0.10.x Feb 13, 2026

seratch removed this from the 0.10.x milestone Feb 26, 2026

habema added 2 commits March 1, 2026 12:58

Merge origin/main into feat/track-tool-origin

3a76abc

address code review

8776b02

chatgpt-codex-connector bot reviewed Mar 1, 2026

View reviewed changes

src/agents/run_internal/run_loop.py Outdated Show resolved Hide resolved

src/agents/run_state.py Outdated Show resolved Hide resolved

update CURRENT_SCHEMA_VERSION to 1.5 and include it in SUPPORTED_SCHE…

e961861

…MA_VERSIONS

chatgpt-codex-connector bot reviewed Mar 1, 2026

View reviewed changes

src/agents/run_internal/run_loop.py Outdated Show resolved Hide resolved

address code review

d649f06

habema marked this pull request as ready for review March 1, 2026 12:38

seratch removed documentation Improvements or additions to documentation feature:voice feature:tracing feature:mcp feature:chat-completions feature:lite-llm feature:realtime feature:sessions project dependencies labels Mar 1, 2026

seratch marked this pull request as draft March 1, 2026 22:45

github-actions bot added feature:mcp feature:realtime labels Mar 1, 2026


		return run_result.final_output

		# Set origin tracking on the FunctionTool created by @function_tool

Conversation

habema commented Dec 28, 2025

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

seratch left a comment

Choose a reason for hiding this comment

Uh oh!

seratch Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

habema Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

seratch Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

habema Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seratch commented Jan 22, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

habema commented Mar 1, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

habema commented Mar 1, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

habema commented Mar 1, 2026

Uh oh!

chatgpt-codex-connector bot commented Mar 1, 2026

Uh oh!

seratch commented Mar 1, 2026

Uh oh!

habema commented Mar 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

habema Jan 5, 2026 •

edited

Loading